/**   
 * Copyright 2011 The Buzz Media, LLC
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.thebuzzmedia.imgscalr;

import java.awt.Color;
import java.awt.Graphics;
import java.awt.Graphics2D;
import java.awt.Image;
import java.awt.RenderingHints;
import java.awt.Transparency;
import java.awt.color.ColorSpace;
import java.awt.geom.AffineTransform;
import java.awt.geom.Rectangle2D;
import java.awt.image.AreaAveragingScaleFilter;
import java.awt.image.BufferedImage;
import java.awt.image.BufferedImageOp;
import java.awt.image.ColorConvertOp;
import java.awt.image.ColorModel;
import java.awt.image.ConvolveOp;
import java.awt.image.ImagingOpException;
import java.awt.image.IndexColorModel;
import java.awt.image.Kernel;
import java.awt.image.RasterFormatException;
import java.awt.image.RescaleOp;

import javax.imageio.ImageIO;

/**
 * Class used to implement performant, high-quality and intelligent image
 * scaling and manipulation algorithms in native Java 2D.
 * <p/>
 * This class utilizes the Java2D "best practices" for image manipulation,
 * ensuring that all operations (even most user-provided {@link BufferedImageOp}
 * s) are hardware accelerated if provided by the platform and host-VM.
 * <p/>
 * <h3>Image Quality</h3>
 * This class implements a few different methods for scaling an image, providing
 * either the best-looking result, the fastest result or a balanced result
 * between the two depending on the scaling hint provided (see {@link Method}).
 * <p/>
 * This class also implements an optimized version of the incremental scaling
 * algorithm presented by Chris Campbell in his <a href="http://today.java
 * .net/pub/a/today/2007/04/03/perils-of-image-getscaledinstance.html">Perils of
 * Image.getScaledInstance()</a> article in order to give the best-looking image
 * resize results (e.g. generating thumbnails that aren't blurry or jagged).
 * <p>
 * The results generated by imgscalr using this method, as compared to a single
 * {@link RenderingHints#VALUE_INTERPOLATION_BICUBIC} scale operation look much
 * better, especially when using the {@link Method#ULTRA_QUALITY} method.
 * <p/>
 * Only when scaling using the {@link Method#AUTOMATIC} method will this class
 * look at the size of the image before selecting an approach to scaling the
 * image. If {@link Method#QUALITY} is specified, the best-looking algorithm
 * possible is always used.
 * <p/>
 * Minor modifications are made to Campbell's original implementation in the
 * form of:
 * <ol>
 * <li>Instead of accepting a user-supplied interpolation method,
 * {@link RenderingHints#VALUE_INTERPOLATION_BICUBIC} interpolation is always
 * used. This was done after A/B comparison testing with large images
 * down-scaled to thumbnail sizes showed noticeable "blurring" when BILINEAR
 * interpolation was used. Given that Campbell's algorithm is only used in
 * QUALITY mode when down-scaling, it was determined that the user's expectation
 * of a much less blurry picture would require that BICUBIC be the default
 * interpolation in order to meet the QUALITY expectation.</li>
 * <li>After each iteration of the do-while loop that incrementally scales the
 * source image down, an explicit effort is made to call
 * {@link BufferedImage#flush()} on the interim temporary {@link BufferedImage}
 * instances created by the algorithm in an attempt to ensure a more complete GC
 * cycle by the VM when cleaning up the temporary instances (this is in addition
 * to disposing of the temporary {@link Graphics2D} references as well).</li>
 * <li>Extensive comments have been added to increase readability of the code.</li>
 * <li>Variable names have been expanded to increase readability of the code.</li>
 * </ol>
 * <p/>
 * <strong>NOTE</strong>: This class does not call {@link BufferedImage#flush()}
 * on any of the <em>source images</em> passed in by calling code; it is up to
 * the original caller to dispose of their source images when they are no longer
 * needed so the VM can most efficiently GC them.
 * <h3>Image Proportions</h3>
 * All scaling operations implemented by this class maintain the proportions of
 * the original image unless a mode of {@link Mode#FIT_EXACT} is specified; in
 * which case the orientation and proportion of the source image is ignored and
 * the image is stretched (if necessary) to fit the exact dimensions given.
 * <p/>
 * When not using {@link Mode#FIT_EXACT}, in order to maintain the
 * proportionality of the original images, this class implements the following
 * behavior:
 * <ol>
 * <li>If the image is LANDSCAPE-oriented or SQUARE, treat the
 * <code>targetWidth</code> as the primary dimension and re-calculate the
 * <code>targetHeight</code> regardless of what is passed in.</li>
 * <li>If image is PORTRAIT-oriented, treat the <code>targetHeight</code> as the
 * primary dimension and re-calculate the <code>targetWidth</code> regardless of
 * what is passed in.</li>
 * <li>If a {@link Mode} value of {@link Mode#FIT_TO_WIDTH} or
 * {@link Mode#FIT_TO_HEIGHT} is passed in to the <code>resize</code> method,
 * the image's orientation is ignored and the scaled image is fit to the
 * preferred dimension by using the value passed in by the user for that
 * dimension and recalculating the other (regardless of image orientation). This
 * is useful, for example, when working with PORTRAIT oriented images that you
 * need to all be the same width or visa-versa (e.g. showing user profile
 * pictures in a directory listing).</li>
 * </ol>
 * <h3>Optimized Image Handling</h3>
 * Java2D provides support for a number of different image types defined as
 * <code>BufferedImage.TYPE_*</code> variables, unfortunately not all image
 * types are supported equally in the Java2D rendering pipeline.
 * <p/>
 * Some more obscure image types either have poor or no support, leading to
 * severely degraded quality and processing performance when an attempt is made
 * by imgscalr to create a scaled instance <em>of the same type</em> as the
 * source image. In many cases, especially when applying {@link BufferedImageOp}
 * s, using poorly supported image types can even lead to exceptions or total
 * corruption of the image (e.g. solid black image).
 * <p/>
 * imgscalr specifically accounts for and automatically hands
 * <strong>ALL</strong> of these pain points for you internally by shuffling all
 * images into one of two types:
 * <ol>
 * <li>{@link BufferedImage#TYPE_INT_RGB}</li>
 * <li>{@link BufferedImage#TYPE_INT_ARGB}</li>
 * </ol>
 * depending on if the source image utilizes transparency or not. This is a
 * recommended approach by the Java2D team for dealing with poorly (or non)
 * supported image types. More can be read about this issue <a href=
 * "http://www.mail-archive.com/java2d-interest@capra.eng.sun.com/msg05621.html"
 * >here</a>.
 * <p/>
 * This is also the reason we recommend using
 * {@link #apply(BufferedImage, BufferedImageOp...)} to apply your own ops to
 * images even if you aren't using imgscalr for anything else.
 * <h3>GIF Transparency</h3>
 * Unfortunately in Java 6 and earlier, support for GIF's
 * {@link IndexColorModel} is sub-par, both in accurate color-selection and in
 * maintaining transparency when moving to an image of type
 * {@link BufferedImage#TYPE_INT_ARGB}; because of this issue when a GIF image
 * is processed by imgscalr and the result saved as a GIF file (instead of PNG),
 * it is possible to lose the alpha channel of a transparent image or in the
 * case of applying an optional {@link BufferedImageOp}, lose the entire picture
 * all together in the result (long standing JDK bugs are filed for all of these
 * issues).
 * <p/>
 * imgscalr currently does nothing to work around this manually because it is a
 * defect in the native platform code itself. Fortunately it looks like the
 * issues are half-fixed in Java 7 and any manual workarounds we could attempt
 * internally are relatively expensive, in the form of hand-creating and setting
 * RGB values pixel-by-pixel with a custom {@link ColorModel} in the scaled
 * image. This would lead to a very measurable negative impact on performance
 * without the caller understanding why.
 * <p>
 * <strong>Workaround</strong>: A workaround to this issue with all version of
 * Java is to simply save a GIF as a PNG; no change to your code needs to be
 * made except when the image is saved out, e.g. using {@link ImageIO}.
 * <p>
 * When a file type of "PNG" is used, both the transparency and high color
 * quality will be maintained as the PNG code path in Java2D is superior to the
 * GIF implementation.
 * <p>
 * If the issue with optional {@link BufferedImageOp}s destroying GIF image
 * content is ever fixed in the platform, saving out resulting images as GIFs
 * should suddenly start working.
 * <p>
 * More can be read about the issue <a
 * href="http://gman.eichberger.de/2007/07/transparent-gifs-in-java.html"
 * >here</a> and <a
 * href="http://ubuntuforums.org/archive/index.php/t-1060128.html">here</a>.
 * <h3>Thread Safety</h3>
 * The {@link Scalr} class is <strong>thread-safe</strong> (as all the methods
 * are <code>static</code>); this class maintains no internal state while
 * performing any of the provided operations and is safe to call simultaneously
 * from multiple threads.
 * <h3>Logging</h3>
 * This class implements all its debug logging via the
 * {@link #log(int, String, Object...)} method. At this time logging is done
 * directly to <code>System.out</code> via the <code>printf</code> method. This
 * allows the logging to be light weight and easy to capture (every imgscalr log
 * message is prefixed with the {@link #LOG_PREFIX} string) while adding no
 * dependencies to the library.
 * <p/>
 * Implementation of logging in this class is as efficient as possible; avoiding
 * any calls to the logger method or passing of arguments if logging is not
 * enabled to avoid the (hidden) cost of constructing the Object[] argument for
 * the varargs-based method call.
 * 
 * @author Riyad Kalla (software@thebuzzmedia.com)
 * @since 1.1
 */
public class Scalr {
	/**
	 * System property name used to define the debug boolean flag.
	 * <p/>
	 * Value is "<code>imgscalr.debug</code>".
	 */
	public static final String DEBUG_PROPERTY_NAME = "imgscalr.debug";
	/**
	 * System property name used to define a custom log prefix.
	 * <p/>
	 * Value is "<code>imgscalr.logPrefix</code>".
	 */
	public static final String LOG_PREFIX_PROPERTY_NAME = "imgscalr.logPrefix";
	/**
	 * Flag used to indicate if debugging output has been enabled by setting the
	 * "<code>imgscalr.debug</code>" system property to <code>true</code>. This
	 * value will be <code>false</code> if the "<code>imgscalr.debug</code>"
	 * system property is undefined or set to <code>false</code>.
	 * <p/>
	 * This property can be set on startup with:<br/>
	 * <code>
	 * -Dimgscalr.debug=true
	 * </code> or by calling {@link System#setProperty(String, String)} to set a
	 * new property value for {@link #DEBUG_PROPERTY_NAME} before this class is
	 * loaded.
	 * <p/>
	 * Default value is <code>false</code>.
	 */
	public static final boolean DEBUG = Boolean.getBoolean(DEBUG_PROPERTY_NAME);

	/**
	 * Prefix to every log message this library logs. Using a well-defined
	 * prefix helps make it easier both visually and programmatically to scan
	 * log files for messages produced by this library.
	 * <p/>
	 * This property can be set on startup with:<br/>
	 * <code>
	 * -Dimgscalr.logPrefix=&lt;YOUR PREFIX HERE&gt;
	 * </code> or by calling {@link System#setProperty(String, String)} to set a
	 * new property value for {@link #LOG_PREFIX_PROPERTY_NAME} before this
	 * class is loaded.
	 * <p/>
	 * Default value is "<code>[imgscalr] </code>" (including the space).
	 */
	public static final String LOG_PREFIX = System.getProperty(LOG_PREFIX_PROPERTY_NAME, "[imgscalr] ");

	/**
	 * A {@link ConvolveOp} using a very light "blur" kernel that acts like an
	 * anti-aliasing filter (softens the image a bit) when applied to an image.
	 * <p/>
	 * A common request by users of the library was that they wished to "soften"
	 * resulting images when scaling them down drastically. After quite a bit of
	 * A/B testing, the kernel used by this Op was selected as the closest match
	 * for the target which was the softer results from the deprecated
	 * {@link AreaAveragingScaleFilter} (which is used internally by the
	 * deprecated {@link Image#getScaledInstance(int, int, int)} method in the
	 * JDK that imgscalr is meant to replace).
	 * <p/>
	 * This ConvolveOp uses a 3x3 kernel with the values:
	 * <table cellpadding="4" border="1">
	 * <tr>
	 * <td>.0f</td>
	 * <td>.08f</td>
	 * <td>.0f</td>
	 * </tr>
	 * <tr>
	 * <td>.08f</td>
	 * <td>.68f</td>
	 * <td>.08f</td>
	 * </tr>
	 * <tr>
	 * <td>.0f</td>
	 * <td>.08f</td>
	 * <td>.0f</td>
	 * </tr>
	 * </table>
	 * <p/>
	 * For those that have worked with ConvolveOps before, this Op uses the
	 * {@link ConvolveOp#EDGE_NO_OP} instruction to not process the pixels along
	 * the very edge of the image (otherwise EDGE_ZERO_FILL would create a
	 * black-border around the image). If you have not worked with a ConvolveOp
	 * before, it just means this default OP will "do the right thing" and not
	 * give you garbage results.
	 * <p/>
	 * This ConvolveOp uses no {@link RenderingHints} values as internally the
	 * {@link ConvolveOp} class only uses hints when doing a color conversion
	 * between the source and destination {@link BufferedImage} targets.
	 * imgscalr allows the {@link ConvolveOp} to create its own destination
	 * image every time, so no color conversion is ever needed and thus no
	 * hints.
	 * <h3>Performance</h3>
	 * Use of this (and other) {@link ConvolveOp}s are hardware accelerated when
	 * possible. For more information on if your image op is hardware
	 * accelerated or not, check the source code of the underlying JDK class
	 * that actually executes the Op code, <a href=
	 * "http://www.docjar.com/html/api/sun/awt/image/ImagingLib.java.html"
	 * >sun.awt.image.ImagingLib</a>.
	 * <h3>Known Issues</h3>
	 * In all versions of Java (tested up to Java 7 preview Build 131), running
	 * this op against a GIF with transparency and attempting to save the
	 * resulting image as a GIF results in a corrupted/empty file. The file must
	 * be saved out as a PNG to maintain the transparency.
	 * 
	 * @since 3.0
	 */
	public static final ConvolveOp OP_ANTIALIAS = new ConvolveOp(
			new Kernel(3, 3, new float[] { .0f, .08f, .0f, .08f, .68f, .08f,
					.0f, .08f, .0f }), ConvolveOp.EDGE_NO_OP, null);

	/**
	 * A {@link RescaleOp} used to make any input image 10% darker.
	 * <p/>
	 * This operation can be applied multiple times in a row if greater than 10%
	 * changes in brightness are desired.
	 * 
	 * @since 4.0
	 */
	public static final RescaleOp OP_DARKER = new RescaleOp(0.9f, 0, null);
	/**
	 * A {@link RescaleOp} used to make any input image 10% brighter.
	 * <p/>
	 * This operation can be applied multiple times in a row if greater than 10%
	 * changes in brightness are desired.
	 * 
	 * @since 4.0
	 */
	public static final RescaleOp OP_BRIGHTER = new RescaleOp(1.1f, 0, null);
	/**
	 * A {@link ColorConvertOp} used to convert any image to a grayscale color
	 * palette.
	 * <p/>
	 * Applying this op multiple times to the same image has no compounding
	 * effects.
	 * 
	 * @since 4.0
	 */
	public static final ColorConvertOp OP_GRAYSCALE = new ColorConvertOp(ColorSpace.getInstance(ColorSpace.CS_GRAY),
	    null);
	/**
	 * Static initializer used to prepare some of the variables used by this
	 * class.
	 */
	static {
		log(0, "Debug output ENABLED");
	}

	/**
	 * Used to define the different scaling hints that the algorithm can use.
	 * 
	 * @author Riyad Kalla (software@thebuzzmedia.com)
	 * @since 1.1
	 */
	public static enum Method {
		/**
		 * Used to indicate that the scaling implementation should decide which
		 * method to use in order to get the best looking scaled image in the
		 * least amount of time.
		 * <p/>
		 * The scaling algorithm will use the
		 * {@link Scalr#THRESHOLD_QUALITY_BALANCED} or
		 * {@link Scalr#THRESHOLD_BALANCED_SPEED} thresholds as cut-offs to
		 * decide between selecting the <code>QUALITY</code>,
		 * <code>BALANCED</code> or <code>SPEED</code> scaling algorithms.
		 * <p/>
		 * By default the thresholds chosen will give nearly the best looking
		 * result in the fastest amount of time. We intend this method to work
		 * for 80% of people looking to scale an image quickly and get a good
		 * looking result.
		 */
		AUTOMATIC,
		/**
		 * Used to indicate that the scaling implementation should scale as fast
		 * as possible and return a result. For smaller images (800px in size)
		 * this can result in noticeable aliasing but it can be a few magnitudes
		 * times faster than using the QUALITY method.
		 */
		SPEED,
		/**
		 * Used to indicate that the scaling implementation should use a scaling
		 * operation balanced between SPEED and QUALITY. Sometimes SPEED looks
		 * too low quality to be useful (e.g. text can become unreadable when
		 * scaled using SPEED) but using QUALITY mode will increase the
		 * processing time too much. This mode provides a "better than SPEED"
		 * quality in a "less than QUALITY" amount of time.
		 */
		BALANCED,
		/**
		 * Used to indicate that the scaling implementation should do everything
		 * it can to create as nice of a result as possible. This approach is
		 * most important for smaller pictures (800px or smaller) and less
		 * important for larger pictures as the difference between this method
		 * and the SPEED method become less and less noticeable as the
		 * source-image size increases. Using the AUTOMATIC method will
		 * automatically prefer the QUALITY method when scaling an image down
		 * below 800px in size.
		 */
		QUALITY,
		/**
		 * Used to indicate that the scaling implementation should go above and
		 * beyond the work done by {@link Method#QUALITY} to make the image look
		 * exceptionally good at the cost of more processing time. This is
		 * especially evident when generating thumbnails of images that look
		 * jagged with some of the other {@link Method}s (even
		 * {@link Method#QUALITY}).
		 */
		ULTRA_QUALITY;
	}

	/**
	 * Used to define the different modes of resizing that the algorithm can
	 * use.
	 * 
	 * @author Riyad Kalla (software@thebuzzmedia.com)
	 * @since 3.1
	 */
	public static enum Mode {
		/**
		 * Used to indicate that the scaling implementation should calculate
		 * dimensions for the resultant image by looking at the image's
		 * orientation and generating proportional dimensions that best fit into
		 * the target width and height given
		 * 
		 * See "Image Proportions" in the {@link Scalr} class description for
		 * more detail.
		 */
		AUTOMATIC,
		/**
		 * Used to fit the image to the exact dimensions given regardless of the
		 * image's proportions. If the dimensions are not proportionally
		 * correct, this will introduce vertical or horizontal stretching to the
		 * image.
		 * <p/>
		 * It is recommended that you use one of the other <code>FIT_TO</code>
		 * modes or {@link Mode#AUTOMATIC} if you want the image to look
		 * correct, but if dimension-fitting is the #1 priority regardless of
		 * how it makes the image look, that is what this mode is for.
		 */
		FIT_EXACT,
		/**
		 * Used to indicate that the scaling implementation should calculate
		 * dimensions for the largest image that fit within the bounding box,
		 * without cropping or distortion, retaining the original proportions.
		 */
		BEST_FIT_BOTH,
		/**
		 * Used to indicate that the scaling implementation should calculate
		 * dimensions for the resultant image that best-fit within the given
		 * width, regardless of the orientation of the image.
		 */
		FIT_TO_WIDTH,
		/**
		 * Used to indicate that the scaling implementation should calculate
		 * dimensions for the resultant image that best-fit within the given
		 * height, regardless of the orientation of the image.
		 */
		FIT_TO_HEIGHT;
	}

	/**
	 * Used to define the different types of rotations that can be applied to an
	 * image during a resize operation.
	 * 
	 * @author Riyad Kalla (software@thebuzzmedia.com)
	 * @since 3.2
	 */
	public static enum Rotation {
		/**
		 * 90-degree, clockwise rotation (to the right). This is equivalent to a
		 * quarter-turn of the image to the right; moving the picture on to its
		 * right side.
		 */
		CW_90,
		/**
		 * 180-degree, clockwise rotation (to the right). This is equivalent to
		 * 1 half-turn of the image to the right; rotating the picture around
		 * until it is upside down from the original position.
		 */
		CW_180,
		/**
		 * 270-degree, clockwise rotation (to the right). This is equivalent to
		 * a quarter-turn of the image to the left; moving the picture on to its
		 * left side.
		 */
		CW_270,
		/**
		 * Flip the image horizontally by reflecting it around the y axis.
		 * <p/>
		 * This is not a standard rotation around a center point, but instead
		 * creates the mirrored reflection of the image horizontally.
		 * <p/>
		 * More specifically, the vertical orientation of the image stays the
		 * same (the top stays on top, and the bottom on bottom), but the right
		 * and left sides flip. This is different than a standard rotation where
		 * the top and bottom would also have been flipped.
		 */
		FLIP_HORZ,
		/**
		 * Flip the image vertically by reflecting it around the x axis.
		 * <p/>
		 * This is not a standard rotation around a center point, but instead
		 * creates the mirrored reflection of the image vertically.
		 * <p/>
		 * More specifically, the horizontal orientation of the image stays the
		 * same (the left stays on the left and the right stays on the right),
		 * but the top and bottom sides flip. This is different than a standard
		 * rotation where the left and right would also have been flipped.
		 */
		FLIP_VERT;
	}

	/**
	 * Threshold (in pixels) at which point the scaling operation using the
	 * {@link Method#AUTOMATIC} method will decide if a {@link Method#BALANCED}
	 * method will be used (if smaller than or equal to threshold) or a
	 * {@link Method#SPEED} method will be used (if larger than threshold).
	 * <p/>
	 * The bigger the image is being scaled to, the less noticeable degradations
	 * in the image becomes and the faster algorithms can be selected.
	 * <p/>
	 * The value of this threshold (1600) was chosen after visual, by-hand, A/B
	 * testing between different types of images scaled with this library; both
	 * photographs and screenshots. It was determined that images below this
	 * size need to use a {@link Method#BALANCED} scale method to look decent in
	 * most all cases while using the faster {@link Method#SPEED} method for
	 * images bigger than this threshold showed no noticeable degradation over a
	 * <code>BALANCED</code> scale.
	 */
	public static final int THRESHOLD_BALANCED_SPEED = 1600;

	/**
	 * Threshold (in pixels) at which point the scaling operation using the
	 * {@link Method#AUTOMATIC} method will decide if a {@link Method#QUALITY}
	 * method will be used (if smaller than or equal to threshold) or a
	 * {@link Method#BALANCED} method will be used (if larger than threshold).
	 * <p/>
	 * The bigger the image is being scaled to, the less noticeable degradations
	 * in the image becomes and the faster algorithms can be selected.
	 * <p/>
	 * The value of this threshold (800) was chosen after visual, by-hand, A/B
	 * testing between different types of images scaled with this library; both
	 * photographs and screenshots. It was determined that images below this
	 * size need to use a {@link Method#QUALITY} scale method to look decent in
	 * most all cases while using the faster {@link Method#BALANCED} method for
	 * images bigger than this threshold showed no noticeable degradation over a
	 * <code>QUALITY</code> scale.
	 */
	public static final int THRESHOLD_QUALITY_BALANCED = 800;

	/**
	 * Used to apply, in the order given, 1 or more {@link BufferedImageOp}s to
	 * a given {@link BufferedImage} and return the result.
	 * <p/>
	 * <strong>Feature</strong>: This implementation works around <a
	 * href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4965606">a
	 * decade-old JDK bug</a> that can cause a {@link RasterFormatException}
	 * when applying a perfectly valid {@link BufferedImageOp}s to images.
	 * <p/>
	 * <strong>Feature</strong>: This implementation also works around
	 * {@link BufferedImageOp}s failing to apply and throwing
	 * {@link ImagingOpException}s when run against a <code>src</code> image
	 * type that is poorly supported. Unfortunately using {@link ImageIO} and
	 * standard Java methods to load images provides no consistency in getting
	 * images in well-supported formats. This method automatically accounts and
	 * corrects for all those problems (if necessary).
	 * <p/>
	 * It is recommended you always use this method to apply any
	 * {@link BufferedImageOp}s instead of relying on directly using the
	 * {@link BufferedImageOp#filter(BufferedImage, BufferedImage)} method.
	 * <p/>
	 * <strong>Performance</strong>: Not all {@link BufferedImageOp}s are
	 * hardware accelerated operations, but many of the most popular (like
	 * {@link ConvolveOp}) are. For more information on if your image op is
	 * hardware accelerated or not, check the source code of the underlying JDK
	 * class that actually executes the Op code, <a href=
	 * "http://www.docjar.com/html/api/sun/awt/image/ImagingLib.java.html"
	 * >sun.awt.image.ImagingLib</a>.
	 * <p/>
	 * <strong>TIP</strong>: This operation leaves the original <code>src</code>
	 * image unmodified. If the caller is done with the <code>src</code> image
	 * after getting the result of this operation, remember to call
	 * {@link BufferedImage#flush()} on the <code>src</code> to free up native
	 * resources and make it easier for the GC to collect the unused image.
	 * 
	 * @param src
	 *            The image that will have the ops applied to it.
	 * @param ops
	 *            <code>1</code> or more ops to apply to the image.
	 * 
	 * @return a new {@link BufferedImage} that represents the <code>src</code>
	 *         with all the given operations applied to it.
	 * 
	 * @throws IllegalArgumentException
	 *             if <code>src</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>ops</code> is <code>null</code> or empty.
	 * @throws ImagingOpException
	 *             if one of the given {@link BufferedImageOp}s fails to apply.
	 *             These exceptions bubble up from the inside of most of the
	 *             {@link BufferedImageOp} implementations and are explicitly
	 *             defined on the imgscalr API to make it easier for callers to
	 *             catch the exception (if they are passing along optional ops
	 *             to be applied). imgscalr takes detailed steps to avoid the
	 *             most common pitfalls that will cause {@link BufferedImageOp}s
	 *             to fail, even when using straight forward JDK-image
	 *             operations.
	 */
	public static BufferedImage apply(BufferedImage src, BufferedImageOp... ops) throws IllegalArgumentException,
	        ImagingOpException {
		long t = -1;
		if (DEBUG)
			t = System.currentTimeMillis();
		if (src == null)
			throw new IllegalArgumentException("src cannot be null");
		if (ops == null || ops.length == 0)
			throw new IllegalArgumentException("ops cannot be null or empty");
		int type = src.getType();
		/*
		 * Ensure the src image is in the best supported image type before we
		 * continue, otherwise it is possible our calls below to getBounds2D and
		 * certainly filter(...) may fail if not.
		 * 
		 * Java2D makes an attempt at applying most BufferedImageOps using
		 * hardware acceleration via the ImagingLib internal library.
		 * 
		 * Unfortunately may of the BufferedImageOp are written to simply fail
		 * with an ImagingOpException if the operation cannot be applied with no
		 * additional information about what went wrong or attempts at
		 * re-applying it in different ways.
		 * 
		 * This is assuming the failing BufferedImageOp even returns a null
		 * image after failing to apply; some simply return a corrupted/black
		 * image that result in no exception and it is up to the user to
		 * discover this.
		 * 
		 * In internal testing, EVERY failure I've ever seen was the result of
		 * the source image being in a poorly-supported BufferedImage Type like
		 * BGR or ABGR (even though it was loaded with ImageIO).
		 * 
		 * To avoid this nasty/stupid surprise with BufferedImageOps, we always
		 * ensure that the src image starts in an optimally supported format
		 * before we try and apply the filter.
		 */
		if (!(type == BufferedImage.TYPE_INT_RGB || type == BufferedImage.TYPE_INT_ARGB))
			src = copyToOptimalImage(src);
		if (DEBUG)
			log(0, "Applying %d BufferedImageOps...", ops.length);
		boolean hasReassignedSrc = false;
		for (int i = 0; i < ops.length; i++) {
			long subT = -1;
			if (DEBUG)
				subT = System.currentTimeMillis();
			BufferedImageOp op = ops[i];
			// Skip null ops instead of throwing an exception.
			if (op == null)
				continue;
			if (DEBUG)
				log(1, "Applying BufferedImageOp [class=%s, toString=%s]...", op.getClass(), op.toString());
			/*
			 * Must use op.getBounds instead of src.getWidth and src.getHeight
			 * because we are trying to create an image big enough to hold the
			 * result of this operation (which may be to scale the image
			 * smaller), in that case the bounds reported by this op and the
			 * bounds reported by the source image will be different.
			 */
			Rectangle2D resultBounds = op.getBounds2D(src);
			// Watch out for flaky/misbehaving ops that fail to work right.
			if (resultBounds == null)
				throw new ImagingOpException(
				    "BufferedImageOp ["
				            + op.toString()
				            + "] getBounds2D(src) returned null bounds for the target image; this should not happen and indicates a problem with application of this type of op.");
			/*
			 * We must manually create the target image; we cannot rely on the
			 * null-destination filter() method to create a valid destination
			 * for us thanks to this JDK bug that has been filed for almost a
			 * decade:
			 * http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4965606
			 */
			BufferedImage dest = createOptimalImage(src, (int) Math.round(resultBounds.getWidth()),
			    (int) Math.round(resultBounds.getHeight()));
			// Perform the operation, update our result to return.
			BufferedImage result = op.filter(src, dest);
			/*
			 * Flush the 'src' image ONLY IF it is one of our interim temporary
			 * images being used when applying 2 or more operations back to
			 * back. We never want to flush the original image passed in.
			 */
			if (hasReassignedSrc)
				src.flush();
			/*
			 * Incase there are more operations to perform, update what we
			 * consider the 'src' reference to our last result so on the next
			 * iteration the next op is applied to this result and not back
			 * against the original src passed in.
			 */
			src = result;
			/*
			 * Keep track of when we re-assign 'src' to an interim temporary
			 * image, so we know when we can explicitly flush it and clean up
			 * references on future iterations.
			 */
			hasReassignedSrc = true;
			if (DEBUG)
				log(1, "Applied BufferedImageOp in %d ms, result [width=%d, height=%d]", System.currentTimeMillis()
				        - subT, result.getWidth(), result.getHeight());
		}
		if (DEBUG)
			log(0, "All %d BufferedImageOps applied in %d ms", ops.length, System.currentTimeMillis() - t);
		return src;
	}

	/**
	 * Used to crop the given <code>src</code> image from the top-left corner
	 * and applying any optional {@link BufferedImageOp}s to the result before
	 * returning it.
	 * <p/>
	 * <strong>TIP</strong>: This operation leaves the original <code>src</code>
	 * image unmodified. If the caller is done with the <code>src</code> image
	 * after getting the result of this operation, remember to call
	 * {@link BufferedImage#flush()} on the <code>src</code> to free up native
	 * resources and make it easier for the GC to collect the unused image.
	 * 
	 * @param src
	 *            The image to crop.
	 * @param width
	 *            The width of the bounding cropping box.
	 * @param height
	 *            The height of the bounding cropping box.
	 * @param ops
	 *            <code>0</code> or more ops to apply to the image. If
	 *            <code>null</code> or empty then <code>src</code> is return
	 *            unmodified.
	 * 
	 * @return a new {@link BufferedImage} representing the cropped region of
	 *         the <code>src</code> image with any optional operations applied
	 *         to it.
	 * 
	 * @throws IllegalArgumentException
	 *             if <code>src</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if any coordinates of the bounding crop box is invalid within
	 *             the bounds of the <code>src</code> image (e.g. negative or
	 *             too big).
	 * @throws ImagingOpException
	 *             if one of the given {@link BufferedImageOp}s fails to apply.
	 *             These exceptions bubble up from the inside of most of the
	 *             {@link BufferedImageOp} implementations and are explicitly
	 *             defined on the imgscalr API to make it easier for callers to
	 *             catch the exception (if they are passing along optional ops
	 *             to be applied). imgscalr takes detailed steps to avoid the
	 *             most common pitfalls that will cause {@link BufferedImageOp}s
	 *             to fail, even when using straight forward JDK-image
	 *             operations.
	 */
	public static BufferedImage crop(BufferedImage src, int width, int height, BufferedImageOp... ops)
	        throws IllegalArgumentException, ImagingOpException {
		return crop(src, 0, 0, width, height, ops);
	}

	/**
	 * Used to crop the given <code>src</code> image and apply any optional
	 * {@link BufferedImageOp}s to it before returning the result.
	 * <p/>
	 * <strong>TIP</strong>: This operation leaves the original <code>src</code>
	 * image unmodified. If the caller is done with the <code>src</code> image
	 * after getting the result of this operation, remember to call
	 * {@link BufferedImage#flush()} on the <code>src</code> to free up native
	 * resources and make it easier for the GC to collect the unused image.
	 * 
	 * @param src
	 *            The image to crop.
	 * @param x
	 *            The x-coordinate of the top-left corner of the bounding box
	 *            used for cropping.
	 * @param y
	 *            The y-coordinate of the top-left corner of the bounding box
	 *            used for cropping.
	 * @param width
	 *            The width of the bounding cropping box.
	 * @param height
	 *            The height of the bounding cropping box.
	 * @param ops
	 *            <code>0</code> or more ops to apply to the image. If
	 *            <code>null</code> or empty then <code>src</code> is return
	 *            unmodified.
	 * 
	 * @return a new {@link BufferedImage} representing the cropped region of
	 *         the <code>src</code> image with any optional operations applied
	 *         to it.
	 * 
	 * @throws IllegalArgumentException
	 *             if <code>src</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if any coordinates of the bounding crop box is invalid within
	 *             the bounds of the <code>src</code> image (e.g. negative or
	 *             too big).
	 * @throws ImagingOpException
	 *             if one of the given {@link BufferedImageOp}s fails to apply.
	 *             These exceptions bubble up from the inside of most of the
	 *             {@link BufferedImageOp} implementations and are explicitly
	 *             defined on the imgscalr API to make it easier for callers to
	 *             catch the exception (if they are passing along optional ops
	 *             to be applied). imgscalr takes detailed steps to avoid the
	 *             most common pitfalls that will cause {@link BufferedImageOp}s
	 *             to fail, even when using straight forward JDK-image
	 *             operations.
	 */
	public static BufferedImage crop(BufferedImage src, int x, int y, int width, int height, BufferedImageOp... ops)
	        throws IllegalArgumentException, ImagingOpException {
		long t = -1;
		if (DEBUG)
			t = System.currentTimeMillis();
		if (src == null)
			throw new IllegalArgumentException("src cannot be null");
		if (x < 0 || y < 0 || width < 0 || height < 0)
			throw new IllegalArgumentException("Invalid crop bounds: x [" + x + "], y [" + y + "], width [" + width
			        + "] and height [" + height + "] must all be >= 0");
		int srcWidth = src.getWidth();
		int srcHeight = src.getHeight();
		if ((x + width) > srcWidth)
			throw new IllegalArgumentException("Invalid crop bounds: x + width [" + (x + width)
			        + "] must be <= src.getWidth() [" + srcWidth + "]");
		if ((y + height) > srcHeight)
			throw new IllegalArgumentException("Invalid crop bounds: y + height [" + (y + height)
			        + "] must be <= src.getHeight() [" + srcHeight + "]");
		if (DEBUG)
			log(0, "Cropping Image [width=%d, height=%d] to [x=%d, y=%d, width=%d, height=%d]...", srcWidth, srcHeight,
			    x, y, width, height);
		// Create a target image of an optimal type to render into.
		BufferedImage result = createOptimalImage(src, width, height);
		Graphics g = result.getGraphics();
		/*
		 * Render the region specified by our crop bounds from the src image
		 * directly into our result image (which is the exact size of the crop
		 * region).
		 */
		g.drawImage(src, 0, 0, width, height, x, y, (x + width), (y + height), null);
		g.dispose();
		if (DEBUG)
			log(0, "Cropped Image in %d ms", System.currentTimeMillis() - t);
		// Apply any optional operations (if specified).
		if (ops != null && ops.length > 0)
			result = apply(result, ops);
		return result;
	}

	/**
	 * Used to apply padding around the edges of an image using
	 * {@link Color#BLACK} to fill the extra padded space and then return the
	 * result.
	 * <p/>
	 * The amount of <code>padding</code> specified is applied to all sides;
	 * more specifically, a <code>padding</code> of <code>2</code> would add 2
	 * extra pixels of space (filled by the given <code>color</code>) on the
	 * top, bottom, left and right sides of the resulting image causing the
	 * result to be 4 pixels wider and 4 pixels taller than the <code>src</code>
	 * image.
	 * <p/>
	 * <strong>TIP</strong>: This operation leaves the original <code>src</code>
	 * image unmodified. If the caller is done with the <code>src</code> image
	 * after getting the result of this operation, remember to call
	 * {@link BufferedImage#flush()} on the <code>src</code> to free up native
	 * resources and make it easier for the GC to collect the unused image.
	 * 
	 * @param src
	 *            The image the padding will be added to.
	 * @param padding
	 *            The number of pixels of padding to add to each side in the
	 *            resulting image. If this value is <code>0</code> then
	 *            <code>src</code> is returned unmodified.
	 * @param ops
	 *            <code>0</code> or more ops to apply to the image. If
	 *            <code>null</code> or empty then <code>src</code> is return
	 *            unmodified.
	 * 
	 * @return a new {@link BufferedImage} representing <code>src</code> with
	 *         the given padding applied to it.
	 * 
	 * @throws IllegalArgumentException
	 *             if <code>src</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>padding</code> is &lt; <code>1</code>.
	 * @throws ImagingOpException
	 *             if one of the given {@link BufferedImageOp}s fails to apply.
	 *             These exceptions bubble up from the inside of most of the
	 *             {@link BufferedImageOp} implementations and are explicitly
	 *             defined on the imgscalr API to make it easier for callers to
	 *             catch the exception (if they are passing along optional ops
	 *             to be applied). imgscalr takes detailed steps to avoid the
	 *             most common pitfalls that will cause {@link BufferedImageOp}s
	 *             to fail, even when using straight forward JDK-image
	 *             operations.
	 */
	public static BufferedImage pad(BufferedImage src, int padding, BufferedImageOp... ops)
	        throws IllegalArgumentException, ImagingOpException {
		return pad(src, padding, Color.BLACK);
	}

	/**
	 * Used to apply padding around the edges of an image using the given color
	 * to fill the extra padded space and then return the result. {@link Color}s
	 * using an alpha channel (i.e. transparency) are supported.
	 * <p/>
	 * The amount of <code>padding</code> specified is applied to all sides;
	 * more specifically, a <code>padding</code> of <code>2</code> would add 2
	 * extra pixels of space (filled by the given <code>color</code>) on the
	 * top, bottom, left and right sides of the resulting image causing the
	 * result to be 4 pixels wider and 4 pixels taller than the <code>src</code>
	 * image.
	 * <p/>
	 * <strong>TIP</strong>: This operation leaves the original <code>src</code>
	 * image unmodified. If the caller is done with the <code>src</code> image
	 * after getting the result of this operation, remember to call
	 * {@link BufferedImage#flush()} on the <code>src</code> to free up native
	 * resources and make it easier for the GC to collect the unused image.
	 * 
	 * @param src
	 *            The image the padding will be added to.
	 * @param padding
	 *            The number of pixels of padding to add to each side in the
	 *            resulting image. If this value is <code>0</code> then
	 *            <code>src</code> is returned unmodified.
	 * @param color
	 *            The color to fill the padded space with. {@link Color}s using
	 *            an alpha channel (i.e. transparency) are supported.
	 * @param ops
	 *            <code>0</code> or more ops to apply to the image. If
	 *            <code>null</code> or empty then <code>src</code> is return
	 *            unmodified.
	 * 
	 * @return a new {@link BufferedImage} representing <code>src</code> with
	 *         the given padding applied to it.
	 * 
	 * @throws IllegalArgumentException
	 *             if <code>src</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>padding</code> is &lt; <code>1</code>.
	 * @throws IllegalArgumentException
	 *             if <code>color</code> is <code>null</code>.
	 * @throws ImagingOpException
	 *             if one of the given {@link BufferedImageOp}s fails to apply.
	 *             These exceptions bubble up from the inside of most of the
	 *             {@link BufferedImageOp} implementations and are explicitly
	 *             defined on the imgscalr API to make it easier for callers to
	 *             catch the exception (if they are passing along optional ops
	 *             to be applied). imgscalr takes detailed steps to avoid the
	 *             most common pitfalls that will cause {@link BufferedImageOp}s
	 *             to fail, even when using straight forward JDK-image
	 *             operations.
	 */
	public static BufferedImage pad(BufferedImage src, int padding, Color color, BufferedImageOp... ops)
	        throws IllegalArgumentException, ImagingOpException {
		long t = -1;
		if (DEBUG)
			t = System.currentTimeMillis();
		if (src == null)
			throw new IllegalArgumentException("src cannot be null");
		if (padding < 1)
			throw new IllegalArgumentException("padding [" + padding + "] must be > 0");
		if (color == null)
			throw new IllegalArgumentException("color cannot be null");
		int srcWidth = src.getWidth();
		int srcHeight = src.getHeight();
		/*
		 * Double the padding to account for all sides of the image. More
		 * specifically, if padding is "1" we add 2 pixels to width and 2 to
		 * height, so we have 1 new pixel of padding all the way around our
		 * image.
		 */
		int sizeDiff = (padding * 2);
		int newWidth = srcWidth + sizeDiff;
		int newHeight = srcHeight + sizeDiff;
		if (DEBUG)
			log(0,
			    "Padding Image from [originalWidth=%d, originalHeight=%d, padding=%d] to [newWidth=%d, newHeight=%d]...",
			    srcWidth, srcHeight, padding, newWidth, newHeight);
		boolean colorHasAlpha = (color.getAlpha() != 255);
		boolean imageHasAlpha = (src.getTransparency() != BufferedImage.OPAQUE);
		BufferedImage result;
		/*
		 * We need to make sure our resulting image that we render into contains
		 * alpha if either our original image OR the padding color we are using
		 * contain it.
		 */
		if (colorHasAlpha || imageHasAlpha) {
			if (DEBUG)
				log(1, "Transparency FOUND in source image or color, using ARGB image type...");
			result = new BufferedImage(newWidth, newHeight, BufferedImage.TYPE_INT_ARGB);
		}
		else {
			if (DEBUG)
				log(1, "Transparency NOT FOUND in source image or color, using RGB image type...");
			result = new BufferedImage(newWidth, newHeight, BufferedImage.TYPE_INT_RGB);
		}
		Graphics g = result.getGraphics();
		// "Clear" the background of the new image with our padding color first.
		g.setColor(color);
		g.fillRect(0, 0, newWidth, newHeight);
		// Draw the image into the center of the new padded image.
		g.drawImage(src, padding, padding, null);
		g.dispose();
		if (DEBUG)
			log(0, "Padding Applied in %d ms", System.currentTimeMillis() - t);
		// Apply any optional operations (if specified).
		if (ops != null && ops.length > 0)
			result = apply(result, ops);
		return result;
	}

	/**
	 * Resize a given image (maintaining its original proportion) to a width and
	 * height no bigger than <code>targetSize</code> and apply the given
	 * {@link BufferedImageOp}s (if any) to the result before returning it.
	 * <p/>
	 * A scaling method of {@link Method#AUTOMATIC} and mode of
	 * {@link Mode#AUTOMATIC} are used.
	 * <p/>
	 * <strong>TIP</strong>: This operation leaves the original <code>src</code>
	 * image unmodified. If the caller is done with the <code>src</code> image
	 * after getting the result of this operation, remember to call
	 * {@link BufferedImage#flush()} on the <code>src</code> to free up native
	 * resources and make it easier for the GC to collect the unused image.
	 * 
	 * @param src
	 *            The image that will be scaled.
	 * @param targetSize
	 *            The target width and height (square) that you wish the image
	 *            to fit within.
	 * @param ops
	 *            <code>0</code> or more optional image operations (e.g.
	 *            sharpen, blur, etc.) that can be applied to the final result
	 *            before returning the image.
	 * 
	 * @return a new {@link BufferedImage} representing the scaled
	 *         <code>src</code> image.
	 * 
	 * @throws IllegalArgumentException
	 *             if <code>src</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>targetSize</code> is &lt; 0.
	 * @throws ImagingOpException
	 *             if one of the given {@link BufferedImageOp}s fails to apply.
	 *             These exceptions bubble up from the inside of most of the
	 *             {@link BufferedImageOp} implementations and are explicitly
	 *             defined on the imgscalr API to make it easier for callers to
	 *             catch the exception (if they are passing along optional ops
	 *             to be applied). imgscalr takes detailed steps to avoid the
	 *             most common pitfalls that will cause {@link BufferedImageOp}s
	 *             to fail, even when using straight forward JDK-image
	 *             operations.
	 */
	public static BufferedImage resize(BufferedImage src, int targetSize, BufferedImageOp... ops)
	        throws IllegalArgumentException, ImagingOpException {
		return resize(src, Method.AUTOMATIC, Mode.AUTOMATIC, targetSize, targetSize, ops);
	}

	/**
	 * Resize a given image (maintaining its original proportion) to a width and
	 * height no bigger than <code>targetSize</code> using the given scaling
	 * method and apply the given {@link BufferedImageOp}s (if any) to the
	 * result before returning it.
	 * <p/>
	 * A mode of {@link Mode#AUTOMATIC} is used.
	 * <p/>
	 * <strong>TIP</strong>: This operation leaves the original <code>src</code>
	 * image unmodified. If the caller is done with the <code>src</code> image
	 * after getting the result of this operation, remember to call
	 * {@link BufferedImage#flush()} on the <code>src</code> to free up native
	 * resources and make it easier for the GC to collect the unused image.
	 * 
	 * @param src
	 *            The image that will be scaled.
	 * @param scalingMethod
	 *            The method used for scaling the image; preferring speed to
	 *            quality or a balance of both.
	 * @param targetSize
	 *            The target width and height (square) that you wish the image
	 *            to fit within.
	 * @param ops
	 *            <code>0</code> or more optional image operations (e.g.
	 *            sharpen, blur, etc.) that can be applied to the final result
	 *            before returning the image.
	 * 
	 * @return a new {@link BufferedImage} representing the scaled
	 *         <code>src</code> image.
	 * 
	 * @throws IllegalArgumentException
	 *             if <code>src</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>scalingMethod</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>targetSize</code> is &lt; 0.
	 * @throws ImagingOpException
	 *             if one of the given {@link BufferedImageOp}s fails to apply.
	 *             These exceptions bubble up from the inside of most of the
	 *             {@link BufferedImageOp} implementations and are explicitly
	 *             defined on the imgscalr API to make it easier for callers to
	 *             catch the exception (if they are passing along optional ops
	 *             to be applied). imgscalr takes detailed steps to avoid the
	 *             most common pitfalls that will cause {@link BufferedImageOp}s
	 *             to fail, even when using straight forward JDK-image
	 *             operations.
	 * 
	 * @see Method
	 */
	public static BufferedImage resize(BufferedImage src, Method scalingMethod, int targetSize, BufferedImageOp... ops)
	        throws IllegalArgumentException, ImagingOpException {
		return resize(src, scalingMethod, Mode.AUTOMATIC, targetSize,
				targetSize, ops);
	}

	/**
	 * Resize a given image (maintaining its original proportion) to a width and
	 * height no bigger than <code>targetSize</code> (or fitting the image to
	 * the given WIDTH or HEIGHT explicitly, depending on the {@link Mode}
	 * specified) and apply the given {@link BufferedImageOp}s (if any) to the
	 * result before returning it.
	 * <p/>
	 * A scaling method of {@link Method#AUTOMATIC} is used.
	 * <p/>
	 * <strong>TIP</strong>: This operation leaves the original <code>src</code>
	 * image unmodified. If the caller is done with the <code>src</code> image
	 * after getting the result of this operation, remember to call
	 * {@link BufferedImage#flush()} on the <code>src</code> to free up native
	 * resources and make it easier for the GC to collect the unused image.
	 * 
	 * @param src
	 *            The image that will be scaled.
	 * @param resizeMode
	 *            Used to indicate how imgscalr should calculate the final
	 *            target size for the image, either fitting the image to the
	 *            given width ({@link Mode#FIT_TO_WIDTH}) or fitting the image
	 *            to the given height ({@link Mode#FIT_TO_HEIGHT}). If
	 *            {@link Mode#AUTOMATIC} is passed in, imgscalr will calculate
	 *            proportional dimensions for the scaled image based on its
	 *            orientation (landscape, square or portrait). Unless you have
	 *            very specific size requirements, most of the time you just
	 *            want to use {@link Mode#AUTOMATIC} to "do the right thing".
	 * @param targetSize
	 *            The target width and height (square) that you wish the image
	 *            to fit within.
	 * @param ops
	 *            <code>0</code> or more optional image operations (e.g.
	 *            sharpen, blur, etc.) that can be applied to the final result
	 *            before returning the image.
	 * 
	 * @return a new {@link BufferedImage} representing the scaled
	 *         <code>src</code> image.
	 * 
	 * @throws IllegalArgumentException
	 *             if <code>src</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>resizeMode</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>targetSize</code> is &lt; 0.
	 * @throws ImagingOpException
	 *             if one of the given {@link BufferedImageOp}s fails to apply.
	 *             These exceptions bubble up from the inside of most of the
	 *             {@link BufferedImageOp} implementations and are explicitly
	 *             defined on the imgscalr API to make it easier for callers to
	 *             catch the exception (if they are passing along optional ops
	 *             to be applied). imgscalr takes detailed steps to avoid the
	 *             most common pitfalls that will cause {@link BufferedImageOp}s
	 *             to fail, even when using straight forward JDK-image
	 *             operations.
	 * 
	 * @see Mode
	 */
	public static BufferedImage resize(BufferedImage src, Mode resizeMode, int targetSize, BufferedImageOp... ops)
	        throws IllegalArgumentException, ImagingOpException {
		return resize(src, Method.AUTOMATIC, resizeMode, targetSize, targetSize, ops);
	}

	/**
	 * Resize a given image (maintaining its original proportion) to a width and
	 * height no bigger than <code>targetSize</code> (or fitting the image to
	 * the given WIDTH or HEIGHT explicitly, depending on the {@link Mode}
	 * specified) using the given scaling method and apply the given
	 * {@link BufferedImageOp}s (if any) to the result before returning it.
	 * <p/>
	 * <strong>TIP</strong>: This operation leaves the original <code>src</code>
	 * image unmodified. If the caller is done with the <code>src</code> image
	 * after getting the result of this operation, remember to call
	 * {@link BufferedImage#flush()} on the <code>src</code> to free up native
	 * resources and make it easier for the GC to collect the unused image.
	 * 
	 * @param src
	 *            The image that will be scaled.
	 * @param scalingMethod
	 *            The method used for scaling the image; preferring speed to
	 *            quality or a balance of both.
	 * @param resizeMode
	 *            Used to indicate how imgscalr should calculate the final
	 *            target size for the image, either fitting the image to the
	 *            given width ({@link Mode#FIT_TO_WIDTH}) or fitting the image
	 *            to the given height ({@link Mode#FIT_TO_HEIGHT}). If
	 *            {@link Mode#AUTOMATIC} is passed in, imgscalr will calculate
	 *            proportional dimensions for the scaled image based on its
	 *            orientation (landscape, square or portrait). Unless you have
	 *            very specific size requirements, most of the time you just
	 *            want to use {@link Mode#AUTOMATIC} to "do the right thing".
	 * @param targetSize
	 *            The target width and height (square) that you wish the image
	 *            to fit within.
	 * @param ops
	 *            <code>0</code> or more optional image operations (e.g.
	 *            sharpen, blur, etc.) that can be applied to the final result
	 *            before returning the image.
	 * 
	 * @return a new {@link BufferedImage} representing the scaled
	 *         <code>src</code> image.
	 * 
	 * @throws IllegalArgumentException
	 *             if <code>src</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>scalingMethod</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>resizeMode</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>targetSize</code> is &lt; 0.
	 * @throws ImagingOpException
	 *             if one of the given {@link BufferedImageOp}s fails to apply.
	 *             These exceptions bubble up from the inside of most of the
	 *             {@link BufferedImageOp} implementations and are explicitly
	 *             defined on the imgscalr API to make it easier for callers to
	 *             catch the exception (if they are passing along optional ops
	 *             to be applied). imgscalr takes detailed steps to avoid the
	 *             most common pitfalls that will cause {@link BufferedImageOp}s
	 *             to fail, even when using straight forward JDK-image
	 *             operations.
	 * 
	 * @see Method
	 * @see Mode
	 */
	public static BufferedImage resize(BufferedImage src, Method scalingMethod,
 Mode resizeMode, int targetSize,
	                                   BufferedImageOp... ops) throws IllegalArgumentException, ImagingOpException {
		return resize(src, scalingMethod, resizeMode, targetSize, targetSize, ops);
	}

	/**
	 * Resize a given image (maintaining its original proportion) to the target
	 * width and height and apply the given {@link BufferedImageOp}s (if any) to
	 * the result before returning it.
	 * <p/>
	 * A scaling method of {@link Method#AUTOMATIC} and mode of
	 * {@link Mode#AUTOMATIC} are used.
	 * <p/>
	 * <strong>TIP</strong>: See the class description to understand how this
	 * class handles recalculation of the <code>targetWidth</code> or
	 * <code>targetHeight</code> depending on the image's orientation in order
	 * to maintain the original proportion.
	 * <p/>
	 * <strong>TIP</strong>: This operation leaves the original <code>src</code>
	 * image unmodified. If the caller is done with the <code>src</code> image
	 * after getting the result of this operation, remember to call
	 * {@link BufferedImage#flush()} on the <code>src</code> to free up native
	 * resources and make it easier for the GC to collect the unused image.
	 * 
	 * @param src
	 *            The image that will be scaled.
	 * @param targetWidth
	 *            The target width that you wish the image to have.
	 * @param targetHeight
	 *            The target height that you wish the image to have.
	 * @param ops
	 *            <code>0</code> or more optional image operations (e.g.
	 *            sharpen, blur, etc.) that can be applied to the final result
	 *            before returning the image.
	 * 
	 * @return a new {@link BufferedImage} representing the scaled
	 *         <code>src</code> image.
	 * 
	 * @throws IllegalArgumentException
	 *             if <code>src</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>targetWidth</code> is &lt; 0 or if
	 *             <code>targetHeight</code> is &lt; 0.
	 * @throws ImagingOpException
	 *             if one of the given {@link BufferedImageOp}s fails to apply.
	 *             These exceptions bubble up from the inside of most of the
	 *             {@link BufferedImageOp} implementations and are explicitly
	 *             defined on the imgscalr API to make it easier for callers to
	 *             catch the exception (if they are passing along optional ops
	 *             to be applied). imgscalr takes detailed steps to avoid the
	 *             most common pitfalls that will cause {@link BufferedImageOp}s
	 *             to fail, even when using straight forward JDK-image
	 *             operations.
	 */
	public static BufferedImage resize(BufferedImage src, int targetWidth,
			int targetHeight, BufferedImageOp... ops)
	        throws IllegalArgumentException, ImagingOpException {
		return resize(src, Method.AUTOMATIC, Mode.AUTOMATIC, targetWidth, targetHeight, ops);
	}

	/**
	 * Resize a given image (maintaining its original proportion) to the target
	 * width and height using the given scaling method and apply the given
	 * {@link BufferedImageOp}s (if any) to the result before returning it.
	 * <p/>
	 * A mode of {@link Mode#AUTOMATIC} is used.
	 * <p/>
	 * <strong>TIP</strong>: See the class description to understand how this
	 * class handles recalculation of the <code>targetWidth</code> or
	 * <code>targetHeight</code> depending on the image's orientation in order
	 * to maintain the original proportion.
	 * <p/>
	 * <strong>TIP</strong>: This operation leaves the original <code>src</code>
	 * image unmodified. If the caller is done with the <code>src</code> image
	 * after getting the result of this operation, remember to call
	 * {@link BufferedImage#flush()} on the <code>src</code> to free up native
	 * resources and make it easier for the GC to collect the unused image.
	 * 
	 * @param src
	 *            The image that will be scaled.
	 * @param scalingMethod
	 *            The method used for scaling the image; preferring speed to
	 *            quality or a balance of both.
	 * @param targetWidth
	 *            The target width that you wish the image to have.
	 * @param targetHeight
	 *            The target height that you wish the image to have.
	 * @param ops
	 *            <code>0</code> or more optional image operations (e.g.
	 *            sharpen, blur, etc.) that can be applied to the final result
	 *            before returning the image.
	 * 
	 * @return a new {@link BufferedImage} representing the scaled
	 *         <code>src</code> image.
	 * 
	 * @throws IllegalArgumentException
	 *             if <code>src</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>scalingMethod</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>targetWidth</code> is &lt; 0 or if
	 *             <code>targetHeight</code> is &lt; 0.
	 * @throws ImagingOpException
	 *             if one of the given {@link BufferedImageOp}s fails to apply.
	 *             These exceptions bubble up from the inside of most of the
	 *             {@link BufferedImageOp} implementations and are explicitly
	 *             defined on the imgscalr API to make it easier for callers to
	 *             catch the exception (if they are passing along optional ops
	 *             to be applied). imgscalr takes detailed steps to avoid the
	 *             most common pitfalls that will cause {@link BufferedImageOp}s
	 *             to fail, even when using straight forward JDK-image
	 *             operations.
	 * 
	 * @see Method
	 */
	public static BufferedImage resize(BufferedImage src, Method scalingMethod,
			int targetWidth, int targetHeight, BufferedImageOp... ops) {
		return resize(src, scalingMethod, Mode.AUTOMATIC, targetWidth, targetHeight, ops);
	}

	/**
	 * Resize a given image (maintaining its original proportion) to the target
	 * width and height (or fitting the image to the given WIDTH or HEIGHT
	 * explicitly, depending on the {@link Mode} specified) and apply the given
	 * {@link BufferedImageOp}s (if any) to the result before returning it.
	 * <p/>
	 * A scaling method of {@link Method#AUTOMATIC} is used.
	 * <p/>
	 * <strong>TIP</strong>: See the class description to understand how this
	 * class handles recalculation of the <code>targetWidth</code> or
	 * <code>targetHeight</code> depending on the image's orientation in order
	 * to maintain the original proportion.
	 * <p/>
	 * <strong>TIP</strong>: This operation leaves the original <code>src</code>
	 * image unmodified. If the caller is done with the <code>src</code> image
	 * after getting the result of this operation, remember to call
	 * {@link BufferedImage#flush()} on the <code>src</code> to free up native
	 * resources and make it easier for the GC to collect the unused image.
	 * 
	 * @param src
	 *            The image that will be scaled.
	 * @param resizeMode
	 *            Used to indicate how imgscalr should calculate the final
	 *            target size for the image, either fitting the image to the
	 *            given width ({@link Mode#FIT_TO_WIDTH}) or fitting the image
	 *            to the given height ({@link Mode#FIT_TO_HEIGHT}). If
	 *            {@link Mode#AUTOMATIC} is passed in, imgscalr will calculate
	 *            proportional dimensions for the scaled image based on its
	 *            orientation (landscape, square or portrait). Unless you have
	 *            very specific size requirements, most of the time you just
	 *            want to use {@link Mode#AUTOMATIC} to "do the right thing".
	 * @param targetWidth
	 *            The target width that you wish the image to have.
	 * @param targetHeight
	 *            The target height that you wish the image to have.
	 * @param ops
	 *            <code>0</code> or more optional image operations (e.g.
	 *            sharpen, blur, etc.) that can be applied to the final result
	 *            before returning the image.
	 * 
	 * @return a new {@link BufferedImage} representing the scaled
	 *         <code>src</code> image.
	 * 
	 * @throws IllegalArgumentException
	 *             if <code>src</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>resizeMode</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>targetWidth</code> is &lt; 0 or if
	 *             <code>targetHeight</code> is &lt; 0.
	 * @throws ImagingOpException
	 *             if one of the given {@link BufferedImageOp}s fails to apply.
	 *             These exceptions bubble up from the inside of most of the
	 *             {@link BufferedImageOp} implementations and are explicitly
	 *             defined on the imgscalr API to make it easier for callers to
	 *             catch the exception (if they are passing along optional ops
	 *             to be applied). imgscalr takes detailed steps to avoid the
	 *             most common pitfalls that will cause {@link BufferedImageOp}s
	 *             to fail, even when using straight forward JDK-image
	 *             operations.
	 * 
	 * @see Mode
	 */
	public static BufferedImage resize(BufferedImage src, Mode resizeMode,
			int targetWidth, int targetHeight, BufferedImageOp... ops)
 throws IllegalArgumentException, ImagingOpException {
		return resize(src, Method.AUTOMATIC, resizeMode, targetWidth,
				targetHeight, ops);
	}

	/**
	 * Resize a given image (maintaining its original proportion) to the target
	 * width and height (or fitting the image to the given WIDTH or HEIGHT
	 * explicitly, depending on the {@link Mode} specified) using the given
	 * scaling method and apply the given {@link BufferedImageOp}s (if any) to
	 * the result before returning it.
	 * <p/>
	 * <strong>TIP</strong>: See the class description to understand how this
	 * class handles recalculation of the <code>targetWidth</code> or
	 * <code>targetHeight</code> depending on the image's orientation in order
	 * to maintain the original proportion.
	 * <p/>
	 * <strong>TIP</strong>: This operation leaves the original <code>src</code>
	 * image unmodified. If the caller is done with the <code>src</code> image
	 * after getting the result of this operation, remember to call
	 * {@link BufferedImage#flush()} on the <code>src</code> to free up native
	 * resources and make it easier for the GC to collect the unused image.
	 * 
	 * @param src
	 *            The image that will be scaled.
	 * @param scalingMethod
	 *            The method used for scaling the image; preferring speed to
	 *            quality or a balance of both.
	 * @param resizeMode
	 *            Used to indicate how imgscalr should calculate the final
	 *            target size for the image, either fitting the image to the
	 *            given width ({@link Mode#FIT_TO_WIDTH}) or fitting the image
	 *            to the given height ({@link Mode#FIT_TO_HEIGHT}). If
	 *            {@link Mode#AUTOMATIC} is passed in, imgscalr will calculate
	 *            proportional dimensions for the scaled image based on its
	 *            orientation (landscape, square or portrait). Unless you have
	 *            very specific size requirements, most of the time you just
	 *            want to use {@link Mode#AUTOMATIC} to "do the right thing".
	 * @param targetWidth
	 *            The target width that you wish the image to have.
	 * @param targetHeight
	 *            The target height that you wish the image to have.
	 * @param ops
	 *            <code>0</code> or more optional image operations (e.g.
	 *            sharpen, blur, etc.) that can be applied to the final result
	 *            before returning the image.
	 * 
	 * @return a new {@link BufferedImage} representing the scaled
	 *         <code>src</code> image.
	 * 
	 * @throws IllegalArgumentException
	 *             if <code>src</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>scalingMethod</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>resizeMode</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>targetWidth</code> is &lt; 0 or if
	 *             <code>targetHeight</code> is &lt; 0.
	 * @throws ImagingOpException
	 *             if one of the given {@link BufferedImageOp}s fails to apply.
	 *             These exceptions bubble up from the inside of most of the
	 *             {@link BufferedImageOp} implementations and are explicitly
	 *             defined on the imgscalr API to make it easier for callers to
	 *             catch the exception (if they are passing along optional ops
	 *             to be applied). imgscalr takes detailed steps to avoid the
	 *             most common pitfalls that will cause {@link BufferedImageOp}s
	 *             to fail, even when using straight forward JDK-image
	 *             operations.
	 * 
	 * @see Method
	 * @see Mode
	 */
	public static BufferedImage resize(BufferedImage src, Method scalingMethod,
			Mode resizeMode, int targetWidth, int targetHeight,
 BufferedImageOp... ops) throws IllegalArgumentException,
	        ImagingOpException {
		long t = -1;
		if (DEBUG)
			t = System.currentTimeMillis();

		if (src == null)
			throw new IllegalArgumentException("src cannot be null");
		if (targetWidth < 0)
			throw new IllegalArgumentException("targetWidth must be >= 0");
		if (targetHeight < 0)
			throw new IllegalArgumentException("targetHeight must be >= 0");
		if (scalingMethod == null)
			throw new IllegalArgumentException(
					"scalingMethod cannot be null. A good default value is Method.AUTOMATIC.");
		if (resizeMode == null)
			throw new IllegalArgumentException(
					"resizeMode cannot be null. A good default value is Mode.AUTOMATIC.");

		BufferedImage result = null;

		int currentWidth = src.getWidth();
		int currentHeight = src.getHeight();

		// <= 1 is a square or landscape-oriented image, > 1 is a portrait.
		float ratio = ((float) currentHeight / (float) currentWidth);

		if (DEBUG)
			log(0, "Resizing Image [size=%dx%d, resizeMode=%s, orientation=%s, ratio(H/W)=%f] to [targetSize=%dx%d]",
					currentWidth, currentHeight, resizeMode,
					(ratio <= 1 ? "Landscape/Square" : "Portrait"), ratio,
					targetWidth, targetHeight);

		/*
		 * First determine if ANY size calculation needs to be done, in the case
		 * of FIT_EXACT, ignore image proportions and orientation and just use
		 * what the user sent in, otherwise the proportion of the picture must
		 * be honored.
		 * 
		 * The way that is done is to figure out if the image is in a
		 * LANDSCAPE/SQUARE or PORTRAIT orientation and depending on its
		 * orientation, use the primary dimension (width for LANDSCAPE/SQUARE
		 * and height for PORTRAIT) to recalculate the alternative (height and
		 * width respectively) value that adheres to the existing ratio.
		 * 
		 * This helps make life easier for the caller as they don't need to
		 * pre-compute proportional dimensions before calling the API, they can
		 * just specify the dimensions they would like the image to roughly fit
		 * within and it will do the right thing without mangling the result.
		 */
		if (resizeMode == Mode.FIT_EXACT) {
			if (DEBUG)
				log(1, "Resize Mode FIT_EXACT used, no width/height checking or re-calculation will be done.");
		}
		else if (resizeMode == Mode.BEST_FIT_BOTH) {
			float requestedHeightScaling = ((float) targetHeight / (float) currentHeight);
			float requestedWidthScaling = ((float) targetWidth / (float) currentWidth);
			float actualScaling = Math.min(requestedHeightScaling, requestedWidthScaling);
			targetHeight = Math.round((float) currentHeight * actualScaling);
			targetWidth = Math.round((float) currentWidth * actualScaling);
			if (targetHeight == currentHeight && targetWidth == currentWidth)
				return src;

			if (DEBUG)
				log(1, "Auto-Corrected width and height based on scalingRatio %d.", actualScaling);
		}
		else {
			if ((ratio <= 1 && resizeMode == Mode.AUTOMATIC) || (resizeMode == Mode.FIT_TO_WIDTH)) {
				// First make sure we need to do any work in the first place
				if (targetWidth == src.getWidth())
					return src;
				// Save for detailed logging (this is cheap).
				int originalTargetHeight = targetHeight;

				/*
				 * Landscape or Square Orientation: Ignore the given height and
				 * re-calculate a proportionally correct value based on the
				 * targetWidth.
				 */
				targetHeight = Math.round((float) targetWidth * ratio);

				if (DEBUG && originalTargetHeight != targetHeight)
					log(1, "Auto-Corrected targetHeight [from=%d to=%d] to honor image proportions.",
					    originalTargetHeight, targetHeight);
			}
			else {
				// First make sure we need to do any work in the first place
				if (targetHeight == src.getHeight())
					return src;

				// Save for detailed logging (this is cheap).
				int originalTargetWidth = targetWidth;

				/*
				 * Portrait Orientation: Ignore the given width and re-calculate
				 * a proportionally correct value based on the targetHeight.
				 */
				targetWidth = Math.round((float) targetHeight / ratio);

				if (DEBUG && originalTargetWidth != targetWidth)
					log(1, "Auto-Corrected targetWidth [from=%d to=%d] to honor image proportions.",
					    originalTargetWidth, targetWidth);
			}
		}

		// If AUTOMATIC was specified, determine the real scaling method.
		if (scalingMethod == Scalr.Method.AUTOMATIC)
			scalingMethod = determineScalingMethod(targetWidth, targetHeight,
					ratio);

		if (DEBUG)
			log(1, "Using Scaling Method: %s", scalingMethod);

		// Now we scale the image
		if (scalingMethod == Scalr.Method.SPEED) {
			result = scaleImage(src, targetWidth, targetHeight,
					RenderingHints.VALUE_INTERPOLATION_NEAREST_NEIGHBOR);
		} else if (scalingMethod == Scalr.Method.BALANCED) {
			result = scaleImage(src, targetWidth, targetHeight,
					RenderingHints.VALUE_INTERPOLATION_BILINEAR);
		}
		else if (scalingMethod == Scalr.Method.QUALITY || scalingMethod == Scalr.Method.ULTRA_QUALITY) {
			/*
			 * If we are scaling up (in either width or height - since we know
			 * the image will stay proportional we just check if either are
			 * being scaled up), directly using a single BICUBIC will give us
			 * better results then using Chris Campbell's incremental scaling
			 * operation (and take a lot less time).
			 * 
			 * If we are scaling down, we must use the incremental scaling
			 * algorithm for the best result.
			 */
			if (targetWidth > currentWidth || targetHeight > currentHeight) {
				if (DEBUG)
					log(1, "QUALITY scale-up, a single BICUBIC scale operation will be used...");

				/*
				 * BILINEAR and BICUBIC look similar the smaller the scale jump
				 * upwards is, if the scale is larger BICUBIC looks sharper and
				 * less fuzzy. But most importantly we have to use BICUBIC to
				 * match the contract of the QUALITY rendering scalingMethod.
				 * This note is just here for anyone reading the code and
				 * wondering how they can speed their own calls up.
				 */
				result = scaleImage(src, targetWidth, targetHeight,
						RenderingHints.VALUE_INTERPOLATION_BICUBIC);
			} else {
				if (DEBUG)
					log(1, "QUALITY scale-down, incremental scaling will be used...");

				/*
				 * Originally we wanted to use BILINEAR interpolation here
				 * because it takes 1/3rd the time that the BICUBIC
				 * interpolation does, however, when scaling large images down
				 * to most sizes bigger than a thumbnail we witnessed noticeable
				 * "softening" in the resultant image with BILINEAR that would
				 * be unexpectedly annoying to a user expecting a "QUALITY"
				 * scale of their original image. Instead BICUBIC was chosen to
				 * honor the contract of a QUALITY scale of the original image.
				 */
				result = scaleImageIncrementally(src, targetWidth,
 targetHeight, scalingMethod,
						RenderingHints.VALUE_INTERPOLATION_BICUBIC);
			}
		}

		if (DEBUG)
			log(0, "Resized Image in %d ms", System.currentTimeMillis() - t);

		// Apply any optional operations (if specified).
		if (ops != null && ops.length > 0)
			result = apply(result, ops);

		return result;
	}

	/**
	 * Used to apply a {@link Rotation} and then <code>0</code> or more
	 * {@link BufferedImageOp}s to a given image and return the result.
	 * <p/>
	 * <strong>TIP</strong>: This operation leaves the original <code>src</code>
	 * image unmodified. If the caller is done with the <code>src</code> image
	 * after getting the result of this operation, remember to call
	 * {@link BufferedImage#flush()} on the <code>src</code> to free up native
	 * resources and make it easier for the GC to collect the unused image.
	 * 
	 * @param src
	 *            The image that will have the rotation applied to it.
	 * @param rotation
	 *            The rotation that will be applied to the image.
	 * @param ops
	 *            Zero or more optional image operations (e.g. sharpen, blur,
	 *            etc.) that can be applied to the final result before returning
	 *            the image.
	 * 
	 * @return a new {@link BufferedImage} representing <code>src</code> rotated
	 *         by the given amount and any optional ops applied to it.
	 * 
	 * @throws IllegalArgumentException
	 *             if <code>src</code> is <code>null</code>.
	 * @throws IllegalArgumentException
	 *             if <code>rotation</code> is <code>null</code>.
	 * @throws ImagingOpException
	 *             if one of the given {@link BufferedImageOp}s fails to apply.
	 *             These exceptions bubble up from the inside of most of the
	 *             {@link BufferedImageOp} implementations and are explicitly
	 *             defined on the imgscalr API to make it easier for callers to
	 *             catch the exception (if they are passing along optional ops
	 *             to be applied). imgscalr takes detailed steps to avoid the
	 *             most common pitfalls that will cause {@link BufferedImageOp}s
	 *             to fail, even when using straight forward JDK-image
	 *             operations.
	 * 
	 * @see Rotation
	 */
	public static BufferedImage rotate(BufferedImage src, Rotation rotation, BufferedImageOp... ops)
	        throws IllegalArgumentException, ImagingOpException {
		long t = -1;
		if (DEBUG)
			t = System.currentTimeMillis();

		if (src == null)
			throw new IllegalArgumentException("src cannot be null");
		if (rotation == null)
			throw new IllegalArgumentException("rotation cannot be null");

		if (DEBUG)
			log(0, "Rotating Image [%s]...", rotation);

		/*
		 * Setup the default width/height values from our image.
		 * 
		 * In the case of a 90 or 270 (-90) degree rotation, these two values
		 * flip-flop and we will correct those cases down below in the switch
		 * statement.
		 */
		int newWidth = src.getWidth();
		int newHeight = src.getHeight();

		/*
		 * We create a transform per operation request as (oddly enough) it ends
		 * up being faster for the VM to create, use and destroy these instances
		 * than it is to re-use a single AffineTransform per-thread via the
		 * AffineTransform.setTo(...) methods which was my first choice (less
		 * object creation); after benchmarking this explicit case and looking
		 * at just how much code gets run inside of setTo() I opted for a new AT
		 * for every rotation.
		 * 
		 * Besides the performance win, trying to safely reuse AffineTransforms
		 * via setTo(...) would have required ThreadLocal instances to avoid
		 * race conditions where two or more resize threads are manipulating the
		 * same transform before applying it.
		 * 
		 * Misusing ThreadLocals are one of the #1 reasons for memory leaks in
		 * server applications and since we have no nice way to hook into the
		 * init/destroy Servlet cycle or any other initialization cycle for this
		 * library to automatically call ThreadLocal.remove() to avoid the
		 * memory leak, it would have made using this library *safely* on the
		 * server side much harder.
		 * 
		 * So we opt for creating individual transforms per rotation op and let
		 * the VM clean them up in a GC. I only clarify all this reasoning here
		 * for anyone else reading this code and being tempted to reuse the AT
		 * instances of performance gains; there aren't any AND you get a lot of
		 * pain along with it.
		 */
		AffineTransform tx = new AffineTransform();

		switch (rotation) {
			case CW_90:
			/*
			 * A 90 or -90 degree rotation will cause the height and width to
			 * flip-flop from the original image to the rotated one.
			 */
				newWidth = src.getHeight();
				newHeight = src.getWidth();
				// Reminder: newWidth == result.getHeight() at this point
				tx.translate(newWidth, 0);
				tx.rotate(Math.toRadians(90));
				break;

			case CW_270:
				/*
				 * A 90 or -90 degree rotation will cause the height and width to
				 * flip-flop from the original image to the rotated one.
				 */
				newWidth = src.getHeight();
				newHeight = src.getWidth();

				// Reminder: newHeight == result.getWidth() at this point
				tx.translate(0, newHeight);
				tx.rotate(Math.toRadians(-90));
				break;

			case CW_180:
				tx.translate(newWidth, newHeight);
				tx.rotate(Math.toRadians(180));
				break;

			case FLIP_HORZ:
				tx.translate(newWidth, 0);
				tx.scale(-1.0, 1.0);
				break;

			case FLIP_VERT:
				tx.translate(0, newHeight);
				tx.scale(1.0, -1.0);
				break;
		}

		// Create our target image we will render the rotated result to.
		BufferedImage result = createOptimalImage(src, newWidth, newHeight);
		Graphics2D g2d = result.createGraphics();

		/*
		 * Render the resultant image to our new rotatedImage buffer, applying
		 * the AffineTransform that we calculated above during rendering so the
		 * pixels from the old position are transposed to the new positions in
		 * the resulting image correctly.
		 */
		g2d.drawImage(src, tx, null);
		g2d.dispose();

		if (DEBUG)
			log(0, "Rotation Applied in %d ms, result [width=%d, height=%d]", System.currentTimeMillis() - t,
			    result.getWidth(), result.getHeight());

		// Apply any optional operations (if specified).
		if (ops != null && ops.length > 0)
			result = apply(result, ops);

		return result;
	}

	/**
	 * Used to write out a useful and well-formatted log message by any piece of
	 * code inside of the imgscalr library.
	 * <p/>
	 * If a message cannot be logged (logging is disabled) then this method
	 * returns immediately.
	 * <p/>
	 * <strong>NOTE</strong>: Because Java will auto-box primitive arguments
	 * into Objects when building out the <code>params</code> array, care should
	 * be taken not to call this method with primitive values unless
	 * {@link Scalr#DEBUG} is <code>true</code>; otherwise the VM will be
	 * spending time performing unnecessary auto-boxing calculations.
	 * 
	 * @param depth
	 *            The indentation level of the log message.
	 * @param message
	 *            The log message in <a href=
	 *            "http://download.oracle.com/javase/6/docs/api/java/util/Formatter.html#syntax"
	 *            >format string syntax</a> that will be logged.
	 * @param params
	 *            The parameters that will be swapped into all the place holders
	 *            in the original messages before being logged.
	 * 
	 * @see Scalr#LOG_PREFIX
	 * @see Scalr#LOG_PREFIX_PROPERTY_NAME
	 */
	protected static void log(int depth, String message, Object... params) {
		if (Scalr.DEBUG) {
			System.out.print(Scalr.LOG_PREFIX);
			for (int i = 0; i < depth; i++)
				System.out.print("\t");
			System.out.printf(message, params);
			System.out.println();
		}
	}

	/**
	 * Used to create a {@link BufferedImage} with the most optimal RGB TYPE (
	 * {@link BufferedImage#TYPE_INT_RGB} or {@link BufferedImage#TYPE_INT_ARGB}
	 * ) capable of being rendered into from the given <code>src</code>. The
	 * width and height of both images will be identical.
	 * <p/>
	 * This does not perform a copy of the image data from <code>src</code> into
	 * the result image; see {@link #copyToOptimalImage(BufferedImage)} for
	 * that.
	 * <p/>
	 * We force all rendering results into one of these two types, avoiding the
	 * case where a source image is of an unsupported (or poorly supported)
	 * format by Java2D causing the rendering result to end up looking terrible
	 * (common with GIFs) or be totally corrupt (e.g. solid black image).
	 * <p/>
	 * Originally reported by Magnus Kvalheim from Movellas when scaling certain
	 * GIF and PNG images.
	 * 
	 * @param src
	 *            The source image that will be analyzed to determine the most
	 *            optimal image type it can be rendered into.
	 * 
	 * @return a new {@link BufferedImage} representing the most optimal target
	 *         image type that <code>src</code> can be rendered into.
	 * 
	 * @see <a
	 *      href="http://www.mail-archive.com/java2d-interest@capra.eng.sun.com/msg05621.html">How
	 *      Java2D handles poorly supported image types</a>
	 * @see <a
	 *      href="http://code.google.com/p/java-image-scaling/source/browse/trunk/src/main/java/com/mortennobel/imagescaling/MultiStepRescaleOp.java">Thanks
	 *      to Morten Nobel for implementation hint</a>
	 */
	protected static BufferedImage createOptimalImage(BufferedImage src) {
		return createOptimalImage(src, src.getWidth(), src.getHeight());
	}

	/**
	 * Used to create a {@link BufferedImage} with the given dimensions and the
	 * most optimal RGB TYPE ( {@link BufferedImage#TYPE_INT_RGB} or
	 * {@link BufferedImage#TYPE_INT_ARGB} ) capable of being rendered into from
	 * the given <code>src</code>.
	 * <p/>
	 * This does not perform a copy of the image data from <code>src</code> into
	 * the result image; see {@link #copyToOptimalImage(BufferedImage)} for
	 * that.
	 * <p/>
	 * We force all rendering results into one of these two types, avoiding the
	 * case where a source image is of an unsupported (or poorly supported)
	 * format by Java2D causing the rendering result to end up looking terrible
	 * (common with GIFs) or be totally corrupt (e.g. solid black image).
	 * <p/>
	 * Originally reported by Magnus Kvalheim from Movellas when scaling certain
	 * GIF and PNG images.
	 * 
	 * @param src
	 *            The source image that will be analyzed to determine the most
	 *            optimal image type it can be rendered into.
	 * @param width
	 *            The width of the newly created resulting image.
	 * @param height
	 *            The height of the newly created resulting image.
	 * 
	 * @return a new {@link BufferedImage} representing the most optimal target
	 *         image type that <code>src</code> can be rendered into.
	 * 
	 * @throws IllegalArgumentException
	 *             if <code>width</code> or <code>height</code> are &lt; 0.
	 * 
	 * @see <a
	 *      href="http://www.mail-archive.com/java2d-interest@capra.eng.sun.com/msg05621.html">How
	 *      Java2D handles poorly supported image types</a>
	 * @see <a
	 *      href="http://code.google.com/p/java-image-scaling/source/browse/trunk/src/main/java/com/mortennobel/imagescaling/MultiStepRescaleOp.java">Thanks
	 *      to Morten Nobel for implementation hint</a>
	 */
	protected static BufferedImage createOptimalImage(BufferedImage src, int width, int height)
	        throws IllegalArgumentException {
		if (width < 0 || height < 0)
			throw new IllegalArgumentException("width [" + width + "] and height [" + height + "] must be >= 0");
		return new BufferedImage(width, height,
		    (src.getTransparency() == Transparency.OPAQUE ? BufferedImage.TYPE_INT_RGB : BufferedImage.TYPE_INT_ARGB));
	}

	/**
	 * Used to copy a {@link BufferedImage} from a non-optimal type into a new
	 * {@link BufferedImage} instance of an optimal type (RGB or ARGB). If
	 * <code>src</code> is already of an optimal type, then it is returned
	 * unmodified.
	 * <p/>
	 * This method is meant to be used by any calling code (imgscalr's or
	 * otherwise) to convert any inbound image from a poorly supported image
	 * type into the 2 most well-supported image types in Java2D (
	 * {@link BufferedImage#TYPE_INT_RGB} or {@link BufferedImage#TYPE_INT_ARGB}
	 * ) in order to ensure all subsequent graphics operations are performed as
	 * efficiently and correctly as possible.
	 * <p/>
	 * When using Java2D to work with image types that are not well supported,
	 * the results can be anything from exceptions bubbling up from the depths
	 * of Java2D to images being completely corrupted and just returned as solid
	 * black.
	 * 
	 * @param src
	 *            The image to copy (if necessary) into an optimally typed
	 *            {@link BufferedImage}.
	 * 
	 * @return a representation of the <code>src</code> image in an optimally
	 *         typed {@link BufferedImage}, otherwise <code>src</code> if it was
	 *         already of an optimal type.
	 * 
	 * @throws IllegalArgumentException
	 *             if <code>src</code> is <code>null</code>.
	 */
	protected static BufferedImage copyToOptimalImage(BufferedImage src) throws IllegalArgumentException {
		if (src == null)
			throw new IllegalArgumentException("src cannot be null");
		// Calculate the type depending on the presence of alpha.
		int type = (src.getTransparency() == Transparency.OPAQUE ? BufferedImage.TYPE_INT_RGB
		        : BufferedImage.TYPE_INT_ARGB);
		BufferedImage result = new BufferedImage(src.getWidth(), src.getHeight(), type);
		// Render the src image into our new optimal source.
		Graphics g = result.getGraphics();
		g.drawImage(src, 0, 0, null);
		g.dispose();
		return result;
	}

	/**
	 * Used to determine the scaling {@link Method} that is best suited for
	 * scaling the image to the targeted dimensions.
	 * <p/>
	 * This method is intended to be used to select a specific scaling
	 * {@link Method} when a {@link Method#AUTOMATIC} method is specified. This
	 * method utilizes the {@link Scalr#THRESHOLD_QUALITY_BALANCED} and
	 * {@link Scalr#THRESHOLD_BALANCED_SPEED} thresholds when selecting which
	 * method should be used by comparing the primary dimension (width or
	 * height) against the threshold and seeing where the image falls. The
	 * primary dimension is determined by looking at the orientation of the
	 * image: landscape or square images use their width and portrait-oriented
	 * images use their height.
	 * 
	 * @param targetWidth
	 *            The target width for the scaled image.
	 * @param targetHeight
	 *            The target height for the scaled image.
	 * @param ratio
	 *            A height/width ratio used to determine the orientation of the
	 *            image so the primary dimension (width or height) can be
	 *            selected to test if it is greater than or less than a
	 *            particular threshold.
	 * 
	 * @return the fastest {@link Method} suited for scaling the image to the
	 *         specified dimensions while maintaining a good-looking result.
	 */
	protected static Method determineScalingMethod(int targetWidth,
			int targetHeight, float ratio) {
		// Get the primary dimension based on the orientation of the image
		int length = (ratio <= 1 ? targetWidth : targetHeight);

		// Default to speed
		Method result = Method.SPEED;

		// Figure out which scalingMethod should be used
		if (length <= Scalr.THRESHOLD_QUALITY_BALANCED)
			result = Method.QUALITY;
		else if (length <= Scalr.THRESHOLD_BALANCED_SPEED)
			result = Method.BALANCED;

		if (DEBUG)
			log(2, "AUTOMATIC scaling method selected: %s", result.name());

		return result;
	}

	/**
	 * Used to implement a straight-forward image-scaling operation using Java
	 * 2D.
	 * <p/>
	 * This method uses the Oracle-encouraged method of
	 * <code>Graphics2D.drawImage(...)</code> to scale the given image with the
	 * given interpolation hint.
	 * 
	 * @param src
	 *            The image that will be scaled.
	 * @param targetWidth
	 *            The target width for the scaled image.
	 * @param targetHeight
	 *            The target height for the scaled image.
	 * @param interpolationHintValue
	 *            The {@link RenderingHints} interpolation value used to
	 *            indicate the method that {@link Graphics2D} should use when
	 *            scaling the image.
	 * 
	 * @return the result of scaling the original <code>src</code> to the given
	 *         dimensions using the given interpolation method.
	 */
	protected static BufferedImage scaleImage(BufferedImage src,
			int targetWidth, int targetHeight, Object interpolationHintValue) {
		// Setup the rendering resources to match the source image's
		BufferedImage result = createOptimalImage(src, targetWidth, targetHeight);
		Graphics2D resultGraphics = result.createGraphics();

		// Scale the image to the new buffer using the specified rendering hint.
		resultGraphics.setRenderingHint(RenderingHints.KEY_INTERPOLATION,
				interpolationHintValue);
		resultGraphics.drawImage(src, 0, 0, targetWidth, targetHeight, null);

		// Just to be clean, explicitly dispose our temporary graphics object
		resultGraphics.dispose();

		// Return the scaled image to the caller.
		return result;
	}

	/**
	 * Used to implement Chris Campbell's incremental-scaling algorithm: <a
	 * href="http://today.java.net/pub/a/today/2007/04/03/perils
	 * -of-image-getscaledinstance
	 * .html">http://today.java.net/pub/a/today/2007/04/03/perils
	 * -of-image-getscaledinstance.html</a>.
	 * <p/>
	 * Modifications to the original algorithm are variable names and comments
	 * added for clarity and the hard-coding of using BICUBIC interpolation as
	 * well as the explicit "flush()" operation on the interim BufferedImage
	 * instances to avoid resource leaking.
	 * 
	 * @param src
	 *            The image that will be scaled.
	 * @param targetWidth
	 *            The target width for the scaled image.
	 * @param targetHeight
	 *            The target height for the scaled image.
	 * @param scalingMethod
	 *            The scaling method specified by the user (or calculated by
	 *            imgscalr) to use for this incremental scaling operation.
	 * @param interpolationHintValue
	 *            The {@link RenderingHints} interpolation value used to
	 *            indicate the method that {@link Graphics2D} should use when
	 *            scaling the image.
	 * 
	 * @return an image scaled to the given dimensions using the given rendering
	 *         hint.
	 */
	protected static BufferedImage scaleImageIncrementally(BufferedImage src,
 int targetWidth, int targetHeight,
	                                                       Method scalingMethod, Object interpolationHintValue) {
		boolean hasReassignedSrc = false;
		int incrementCount = 0;
		int currentWidth = src.getWidth();
		int currentHeight = src.getHeight();

		/*
		 * The original QUALITY mode, representing Chris Campbell's algorithm,
		 * is to step down by 1/2s every time when scaling the image
		 * incrementally. Users pointed out that using this method to scale
		 * images with noticeable straight lines left them really jagged in
		 * smaller thumbnail format.
		 * 
		 * After investigation it was discovered that scaling incrementally by
		 * smaller increments was the ONLY way to make the thumbnail sized
		 * images look less jagged and more accurate; almost matching the
		 * accuracy of Mac's built in thumbnail generation which is the highest
		 * quality resize I've come across (better than GIMP Lanczos3 and
		 * Windows 7).
		 * 
		 * A divisor of 7 was chose as using 5 still left some jaggedness in the
		 * image while a divisor of 8 or higher made the resulting thumbnail too
		 * soft; like our OP_ANTIALIAS convolve op had been forcibly applied to
		 * the result even if the user didn't want it that soft.
		 * 
		 * Using a divisor of 7 for the ULTRA_QUALITY seemed to be the sweet
		 * spot.
		 * 
		 * NOTE: Below when the actual fraction is used to calculate the small
		 * portion to subtract from the current dimension, this is a
		 * progressively smaller and smaller chunk. When the code was changed to
		 * do a linear reduction of the image of equal steps for each
		 * incremental resize (e.g. say 50px each time) the result was
		 * significantly worse than the progressive approach used below; even
		 * when a very high number of incremental steps (13) was tested.
		 */
		int fraction = (scalingMethod == Method.ULTRA_QUALITY ? 7 : 2);
		do {
			int prevCurrentWidth = currentWidth;
			int prevCurrentHeight = currentHeight;
			/*
			 * If the current width is bigger than our target, cut it in half
			 * and sample again.
			 */
			if (currentWidth > targetWidth) {
				currentWidth -= (currentWidth / fraction);

				/*
				 * If we cut the width too far it means we are on our last
				 * iteration. Just set it to the target width and finish up.
				 */
				if (currentWidth < targetWidth)
					currentWidth = targetWidth;
			}

			/*
			 * If the current height is bigger than our target, cut it in half
			 * and sample again.
			 */

			if (currentHeight > targetHeight) {
				currentHeight -= (currentHeight / fraction);

				/*
				 * If we cut the height too far it means we are on our last
				 * iteration. Just set it to the target height and finish up.
				 */

				if (currentHeight < targetHeight)
					currentHeight = targetHeight;
			}

			/*
			 * Stop when we cannot incrementally step down anymore.
			 * 
			 * This used to use a || condition, but that would cause problems
			 * when using FIT_EXACT such that sometimes the width OR height
			 * would not change between iterations, but the other dimension
			 * would (e.g. resizing 500x500 to 500x250).
			 * 
			 * Now changing this to an && condition requires that both
			 * dimensions do not change between a resize iteration before we
			 * consider ourselves done.
			 */
			if (prevCurrentWidth == currentWidth && prevCurrentHeight == currentHeight)
				break;
			if (DEBUG)
				log(2, "Scaling from [%d x %d] to [%d x %d]", prevCurrentWidth, prevCurrentHeight, currentWidth,
				    currentHeight);
			// Render the incremental scaled image.
			BufferedImage incrementalImage = scaleImage(src, currentWidth,
					currentHeight, interpolationHintValue);

			/*
			 * Before re-assigning our interim (partially scaled)
			 * incrementalImage to be the new src image before we iterate around
			 * again to process it down further, we want to flush() the previous
			 * src image IF (and only IF) it was one of our own temporary
			 * BufferedImages created during this incremental down-sampling
			 * cycle. If it wasn't one of ours, then it was the original
			 * caller-supplied BufferedImage in which case we don't want to
			 * flush() it and just leave it alone.
			 */
			if (hasReassignedSrc)
				src.flush();

			/*
			 * Now treat our incremental partially scaled image as the src image
			 * and cycle through our loop again to do another incremental
			 * scaling of it (if necessary).
			 */
			src = incrementalImage;

			/*
			 * Keep track of us re-assigning the original caller-supplied source
			 * image with one of our interim BufferedImages so we know when to
			 * explicitly flush the interim "src" on the next cycle through.
			 */
			hasReassignedSrc = true;

			// Track how many times we go through this cycle to scale the image.
			incrementCount++;
		} while (currentWidth != targetWidth || currentHeight != targetHeight);

		if (DEBUG)
			log(2, "Incrementally Scaled Image in %d steps.", incrementCount);

		/*
		 * Once the loop has exited, the src image argument is now our scaled
		 * result image that we want to return.
		 */
		return src;
	}
}